When you create and use a widget application, you do the following things:
You must first build a widget hierarchy using the WIDGET_* functions. Start by creating a top-level base with the WIDGET_BASE function.
Combine other widget creation functions — WIDGET_BUTTON, CW_PDMENU, etc. — to create and organize the user interface of your widget application. At this point, the widgets are unrealized — they exist only as IDL widget records — and nothing has been created or displayed on the screen.
Note: Widget applications can include multiple widget hierarchies headed by multiple top-level base widgets. See Using Multiple Widget Hierarchies for more on creating a hierarchy of widget hierarchies.
In order for a widget application to do anything, you must provide a routine that examines events, determines what action to take, and implements that action. Actions may involve computation, graphics display, or updates to the widget interface itself.
For best performance, event processing routines must run and return to the calling routine as quickly as possible. Widgets won’t respond to user input while the event-processing routine is running. Widget-based programs should wait for user-generated events, handle them as quickly as possible, and return to wait for more events. Event processing is discussed in detail in Widget Event Processing.
Event handling routines can manipulate widgets via the WIDGET_CONTROL procedure. Possible actions include the following:
To convert the IDL widget records representing your widget hierarchy into a set of platform-specific user interface toolkit elements, use the REALIZE keyword to the WIDGET_CONTROL procedure. Unless you have specifically unmapped the widgets before realizing them, the REALIZE keyword causes the widgets to be displayed on screen. See Manipulating Widgets for additional details.
Your widget application waits for events to be reported to it and reacts as specified in the event handling routine after being registered with the XMANAGER procedure.
Events are obtained by XMANAGER via the WIDGET_EVENT function and passed to the calling routine (your event handler) in the form of an IDL structure variable. Each type of widget returns a different type of structure, as described in the documentation for the individual widget creation functions in the IDL Reference Guide. Every event structure has three common elements: long integers named ID, TOP, and HANDLER:
When an event occurs, XMANAGER arranges for the event structure to be passed to an event-handling procedure specified by the program, and the event handler takes some appropriate action based on the event. This means that multiple widget applications can run simultaneously — XMANAGER arranges for the events be dispatched to the appropriate routine.
Once the widget application has been realized and registered with XMANAGER, the user can interact with the application to accomplish whatever tasks the application is designed to accomplish.
When the application has finished (usually when the user clicks on a “Done” or “Quit” button), destroy the widget hierarchy using the DESTROY keyword to the WIDGET_CONTROL procedure. This causes all resources related to the hierarchy to be freed and removes it from the screen.